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Particle  Tracking  Model  (PTM)  in  the  SMS: 

III.  Tutorial  with  Examples 


PURPOSE:  This  Dredging  Operations  and  Engineering  Research  (DOER)  Technical  Note  (TN) 
is  a  tutorial  with  examples  of  the  PTM,  developed  jointly  by  the  Coastal  Inlets  Research  Program 
(CIRP)  and  DOER  Program.  This  note  is  applicable  to  Version  1.0  of  PTM.  Demirbilek  et  al. 
(2005a)  describe  the  PTM  interface,  and  an  overview  of  features  and  capabilities  of  the  PTM  is 
presented  in  Demirbilek  et  al.  (2005b).  The  theoretical  formulation  and  implementation  of  the 
PTM  are  given  in  a  technical  report  (MacDonald  and  Davies,  in  preparation). 

INTRODUCTION:  The  PTM  is  a  Lagrangian  particle-tracking  model  that  is  part  of  the  U.S. 
Army  Corps  of  Engineers  (USACE)  Surface  Water  Modeling  System,  SMS  (Zundel  2005, 
Zundel  et  al.  1998).  It  employs  a  Lagrangian  method  of  tracking  particle  pathways  to  estimate 
migration  of  sediment  particles  as  influenced  by  waves  and  currents.  For  its  input,  the  PTM 
requires  a  geometric  surface  defining  the  bottom  elevation  (depth)  over  which  water  level, 
current  velocity  vectors,  and  waves  are  available  at  each  point  in  the  modeling  domain.  The  user 
specifies  sediment  sources  and  model  parameters  to  perform  a  PTM  simulation  within  the  SMS 
for  a  given  set  of  hydrodynamic  input  (waves,  water  levels,  and  currents).  The  SMS  includes 
commands  for  layout  of  the  sediment  sources,  specification  of  the  numerical  parameters,  and 
management  of  the  Eulerian  quantities  (water  depth,  surface  elevation,  current  velocity). 

This  document  describes  typical  steps  and  methodologies  users  can  employ  when  performing  a 
PTM  simulation.  The  water  level,  velocity,  and  wave  fields  must  be  simulated  or  specified  prior 
to  constructing  a  PTM  simulation  in  SMS.  This  document  provides  instructions  for  constructing 
a  PTM  simulation,  including  definition  of  particle  sources,  specification  of  model  options  and 
parameters,  and  coordination  of  timing  for  various  inputs  to  the  simulation.  Commentary  is 
provided  to  explain  the  underlying  methodologies  and  reasoning  for  each  step. 

LOADING  EULERIAN  DATA:  Eulerian  data  define  the  input  bathymetry  and  domain 
boundary  definition  as  well  as  input  wave  and  current  conditions.  The  PTM  reads  these  from 
input  files.  Wave  and  hydrodynamic  analyses  must  be  performed  prior  to  the  PTM  simulation. 
At  present,  the  PTM  requires  a  computation  domain  defined  in  the  form  of  an  Inlet  Modeling 
System  (IMS)  -ADCIRC  (Luettich  et  al.  1992)  grid  file,  with  an  XMDF  (Jones  et  al.  2004)  data 
file  containing  water  surface  elevations  and  currents.  If  wave  input  is  desired,  STWAVE  (Smith 
et  al.  2001)  is  the  default  wave  model,  and  the  user  can  provide  PTM  an  STWAVE  grid  and  the 
associated  wave  field  file.  The  user  can  also  use  SMS  to  convert  result  files  from  other 
hydrodynamic  or  wave  models  to  these  required  formats  prior  to  using  them  in  a  PTM 
application. 

The  example  simulation  files  used  in  this  tutorial  come  from  an  analysis  performed  for  a 
hypothetical  generic  estuary.  Required  PTM  input  files  from  the  IMS-ADCIRC  and  STWAVE 
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simulations  are  provided  as  part  of  the  standard  tutorials  distributed  with  the  SMS  (version  9.0) 
package.  These  files  are  also  available  for  downloading  at  http://el.erdc.usace.army.mil/dots/ 
doer/doer.html. 

The  grid  file  (estuary. grd  in  fort.  14  format)  defines  the  domain  of  the  PTM  simulation.  It 
includes  the  coordinate  location  and  bathymetric  elevation  for  each  node  in  the  grid.  The  XMDF 
format  hydrodynamic  file  (estuary_tide.h5)  includes  water  surface  elevations  and  current  values 
for  each  node  at  30-min  intervals.  These  water  levels  and  currents  are  required  input  for  the 
PTM.  After  launching  the  SMS,  the  first  step  in  creating  a  PTM  simulation  is  to  select  and  load 
the  grid  file,  thus  providing  a  framework  for  all  other  Eulerian  inputs  and  outputs.  To  do  this,  go 
to  the  File\Open  and  select  the  file  “estuary.grd”  in  SMS.  Repeat  the  command  to  select 
“estuary_tide.h5”  to  load  the  hydrodynamic  solution.  The  data  will  be  displayed  in  SMS  as 
shown  in  Figure  1. 


Figure  1 .  Hydrodynamic  mesh  and  solution  data  sets  visible  in  the  Project  Explorer  window 

ADCIRC  output  files  can  be  large.  Therefore,  it  may  be  advantageous  to  trim  spatial  and 
temporal  range  of  ADCIRC  output  to  create  PTM  hydrodynamic  input  files.  This  can  be 
performed  from  within  SMS  (Zundel  2005).  Care  must  be  taken  not  to  spatially  trim  too  much 
of  the  grid  because  once  particles  reach  the  edge  of  the  domain,  they  are  lost  to  the  simulation. 
Therefore,  the  trimming  of  ADCIRC  output  should  not  result  in  particles  leaving  the  domain 
unless  the  flow  patterns  could  keep  the  particles  from  returning  to  the  area  of  interest. 
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The  PTM  interpolates  the  hydrodynamic  solution  data  to  the  Lagrangian  particle  locations. 
Therefore,  the  locations  of  the  ADCIRC  nodes  are  not  important  for  display.  In  fact,  they  tend  to 

clutter  up  the  image,  so  it  may  be  useful  to  turn  them  off,  by  selecting  the  Display  Options  'D' 
macro  and  turning  off  the  Elements  toggle.  Make  sure  the  Nodes  toggle  is  also  off.  Turn  on 
contours  (the  Contours  toggle)  and  the  velocity  vectors  ( Vectors  toggle).  Next  click  on  the 
Vectors  tab  of  the  Display  Options  dialog  and  select  the  option  to  display  vectors  on  a  grid,  and 
click  the  OK  button.  The  vectors  that  appear  on  the  screen  illustrate  the  nature  of  the  flow  field 
for  the  selected  time-step.  Note  that  at  the  first  time-step,  there  is  little  circulation  due  to  the 
ramping  of  the  forcing  condition.  Users  may  also  need  to  adjust  the  settings  for  vector  display. 
The  image  shown  in  Figure  2  displays  vectors  on  a  20-  by  20-pixel  grid  with  minimum  and 
maximum  vector  lengths  of  10  and  80,  respectively. 


Figure  2.  View  after  hiding  ADCIRC  grid  and  showing  vectors 


If  the  modeler  is  not  familiar  with  the  hydrodynamics  that  have  been  computed  for  the  domain, 
he/she  may  want  to  examine  the  flow  data  that  are  driving  the  PTM  simulation  by  selecting  the 
data  sets  from  the  Project  Explorer  (tree  on  the  left  side  of  the  SMS  screen).  This  PTM 
simulation  will  use  the  “tide  only  velocity”  data  set,  and  the  simulation  will  start  at  the  time 
value  172,800  sec.  (explained  later).  To  view  currents  that  will  be  used  by  the  PTM,  click  on 
“tide  only  velocity”  in  the  Project  Explorer  to  select  it  as  the  active  vector  set  and  click  on  “tide 
only  vmag”  to  select  it  as  the  active  scalar  set.  Then  choose  172,800  as  the  active  time-step 
(below  the  tree).  Figure  2  shows  the  view  that  will  result.  Note  that  the  names  “tide  only  vmag” 
and  “tide  only  velocity”  in  the  Project  Explorer  panel  on  the  left  are  bold.  This  indicates  that 
they  are  the  data  sets  displayed  in  the  image. 

This  simulation  will  examine  particle  movement  from  the  coastline  just  east  of  the  mouth  of  the 
estuary.  Figure  3  shows  a  zoomed  image  of  the  portion  of  the  domain  involved  in  the  Lagrangian 

calculations.  Zoom  into  this  portion  of  the  display  using  the  Zoom  tool  5. 
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Figure  3.  Zoomed  view  after  hiding  ADCIRC  grid  and  showing  velocity  vectors 


ADCIRC  time  series  output  includes  a  time  stamp  (in  seconds)  for  each  output  interval.  These 
time  values  are  referenced  to  a  starting  date,  which  has  been  used  to  reference  tidal  constituents. 
Since  this  example  does  not  represent  an  actual  location,  a  reference  date  has  been  created. 
Therefore,  one  can  say  the  time-steps  are  referenced  to  9  February  2004  at  midnight  (12:00  am). 
This  date  corresponds  to  time  zero  (0)  in  the  hydrodynamics.  The  solution  file  (“*.h5”)  begins  at 
the  time-step  value  of  1,800  sec.  This  corresponds  to  12:30  am  on  9  February  2004.  The  first 
24  hr  of  solution  include  the  ADCIRC  ramp.  Over  these  time-steps,  ADCIRC  increases  the  tidal 
forcing  function  from  zero  to  the  true  forcing.  For  that  reason,  the  first  day  should  not  be  used  in 
the  PTM  simulation;  the  first  two  days  will  be  skipped  and  the  PTM  simulation  will  start  at  the 
time  value  of  172,800  sec  (2  days),  which  corresponds  to  midnight  on  11  February  2004.  Just 
over  two  days  of  the  data  will  be  used  in  this  PTM  simulation. 

A  PTM  simulation  requires  specifying  the  actual  date  and  time  values  for  the  simulation. 
Because  ADCIRC  data  are  referenced  to  a  relative  start  time  (t=0),  it  is  necessary  to  specify  the 
hydrodynamic  date/time  stamp  to  align  it  with  the  PTM  time.  Table  1  displays  the  schedule  for 
the  events  that  will  be  included  in  the  simulation.  These  include  the  hydrodynamics,  waves,  and 
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simulated  sediment  particle  sources.  The  PTM  calculations  start  after  the  first  hydrodynamic 
output  time-step. 


Table  1 

Chronology  of  PTM  Simulation 

Time 

Date 

Seconds 

Event 

12:00  am 

9  Feb  2004 

0 

Hydrodynamic  reference  time  (0  sec  in  ADCIRC) 

12:00  am 

9  Feb  2004 

0 

Beginning  time  for  wave  simulation  data 

12:00  am 

10  Feb  2004 

86,400 

End  of  ramping  calculations 

12:00  am 

1 1  Feb  2004 

172,800 

PTM  Simulation  Starts  -  Instantaneous  Particle  Source 
Emits  Particles 

12:00  am 

13  Feb  2004 

345,600 

End  of  PTM  and  ADCIRC  Simulation 

DEFINE  THE  SEDIMENT  PARTICLE  SOURCES:  In  this  example,  a  short-duration  line 
source  is  used  to  represent  nearshore  placement  of  dredged  material.  An  SMS  feature  arc  (or 
point)  is  used  to  define  the  PTM  source  location.  To  create  a  PTM  source  using  an  SMS  feature 
arc,  a  PTM- type  coverage  must  first  be  defined  as  follows: 

•  In  the  Project  Explorer  (tree  window  in  the  left  panel)  right-click  on  the  “default  coverage.” 
Select  “Rename”  and  then  type  “Placement  Option  1 .” 

•  Right-click  on  the  coverage  again  and  move  the  cursor  to  the  “Type”  item.  A  pop-up  menu 
will  appear.  Select  “PTM”  as  the  type. 

•  Left-click  on  the  coverage  to  make  it  active  and  to  activate  the  Map  module. 

Create  a  feature  arc  by  selecting  the  Create  Arc  tool  •  .  This  tool  bar  is  on  the  panel  on  the  left 
side  of  the  SMS  graphics  window.  Click  in  the  mouth  of  the  estuary  (e.g.,  the  southern  left  point 
shown  in  Figure  4)  and  then  double-click  at  the  right  point.  SMS  creates  an  arc  between  the  two 
selected  points.  These  steps  are  illustrated  in  Figure  4. 

The  PTM  is  used  in  this  example  to  predict  pathways  and  fate  of  material  placed  along  this  line. 
The  exact  positions  shown  are  not  crucial.  It  is  important  to  place  the  source  inside  the 
computational  domain  so  that  the  generated  particles  are  in  water.  For  reference,  the  coordinates 
selected  in  this  example  were  (x=-4,000  m  y=l  1,700  m)  and  (x=950  m  y=12,000  m).  The 
specified  line  could  represent  a  proposed  placement  location  for  material  dredged  from  the 
mouth  of  the  estuary.  In  this  case,  the  line  varies  from  the  high-velocity  inlet  to  the  calmer  shore 
to  illustrate  the  variation  in  particle  activity. 

After  specifying  the  location  of  the  source,  it  is  necessary  to  set  the  point  source  attributes.  To 
do  this,  go  to  the  Select  Feature  Arc  R  tool,  click  on  the  feature  arc,  and  choose  the  Feature 
Objects\Attributes  command.  This  displays  the  Line  Source  Properties  dialog  (Figure  5).  Each 
row  of  the  dialog  represents  a  change  over  time  in  the  source.  Each  column  defines  an  attribute 
of  those  particles. 
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Figure  4.  Location  of  the  particle  source 


Figure  5.  Settings  for  line  source 


The  first  line  in  Figure  5  defines  the  time  when  the  source  begins  to  generate  particles.  Double¬ 
clicking  on  one  of  the  date  or  time  entries  and  then  using  the  left  and  right  arrow  keys  in  the  first 
column  allows  the  user  to  enter  2/11/2004  12:00:00  AM  as  shown  in  Figure  5.  The  second, 
third,  fifth,  and  sixth  columns  show  the  coordinates  of  the  segment  endpoints.  The  particles 
generated  are  centered  around  this  line.  The  user  can  edit  these  locations,  and  change  the 
location  of  the  feature  arc  in  this  spreadsheet.  Enter  the  values  specified  above  to  move  the 
feature  arc  to  the  specified  location.  By  changing  the  location  in  different  rows,  the  location  of 
the  particle  source  can  move  over  time.  The  fourth  and  seventh  columns  specify  the  centroidal 
elevation;  enter  a  value  of  1.0  to  indicate  that  material  will  be  released  1.0  m  above  the  bed.  The 
eighth  column  is  the  mass  of  each  particle  tracked  by  the  PTM.  In  actuality,  this  particle  is  a 
cluster  of  particles.  Each  particle  cluster  has  a  characteristic  grain  size  that  controls  how  the 
particle  acts.  The  mass  entered  in  column  8  helps  to  account  for  more  material.  Enter  a  value  of 
1.0  to  tell  the  PTM  to  create  particle  clusters  of  1.0  kg  mass. 
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The  ninth  column  specifies  the  radius  (enter  50.0  m)  in  the  horizontal  plane  to  distribute 
particles,  using  a  Gaussian  distribution  type.  The  tenth  column  specifies  the  vertical  distance 
(enter  1.0  m)  to  distribute  particles  using  a  linear  distribution.  The  eleventh  column  controls  the 
number  of  particles  (or  particle  clusters).  It  allows  the  user  to  specify  the  rate  of  mass  of  the 
material  to  be  released  per  meter  per  second  (enter  0.002  kg/m/sec,  which  yields  0.002*5000  m 
(length  of  horizontal  line  source)  or  10.0  particles/sec,  each  with  a  mass  of  1.0  kg).  The  twelfth 
column  is  the  characteristic  particle  grain  size  in  millimeters,  and  in  this  case,  d$o  =0.19  mm. 
The  thirteenth  column  specifies  the  standard  deviation  value  of  the  characteristic  grain  size  by 
entering  a  value  between  0.0  and  1.0.  Enter  0.85  in  this  example.  This  allows  variation  from 
one  particle  cluster  to  the  next.  Finally,  the  last  column  specifies  the  material  density  (enter 
2,600  kg/m3).  This  entire  line  of  data  defines  the  start  time  and  conditions  for  the  source. 

Select  the  entire  line  just  created  in  the  Line  Source  Property  dialog  box.  Copy  and  paste  the 
data  to  the  second  line.  Change  the  time  of  the  second  line  to  1 1  February  2004  as  shown  in 
Figure  5.  Note  slashes  are  used  in  the  dialogs  for  specifying  time  stamps  (i.e.,  2/11/2004 
12:00:50  AM  in  place  of  11  February  2004).  This  defines  the  end  time  for  this  source  to  be 
50  sec  after  it  was  turned  on.  By  this  time,  approximately  500  particles  (50  sec  * 
10.0  particles/sec)  have  been  generated.  Particle  generation  can  also  be  designated  as  time 
varying  by  changing  the  input  parameters  (such  as  the  rate)  in  the  second  line. 

Copy  the  entire  line  to  the  third  line.  Change  the  time  of  the  third  line  to  2/11/2004 
12:00:51  AM,  and  change  the  rate  to  0.  This  turns  off  the  source.  Click  on  the  OK  button  to 
complete  the  specification  of  particle  sources.  In  this  example,  the  first  line  starts  a  source,  the 
second  line  specifies  the  duration  of  the  source  to  remain  active,  and  the  third  line  shuts  down  the 
source.  It  is  recommended  that  users  follow  this  standard  procedure  for  specifying  sources  to  the 
PTM. 

SET  MODEL  PARAMETERS:  The  user  must  also  specify  the  model  parameters  for  a  PTM 
simulation.  Follow  these  steps: 

•  Select  the  Particle  module  ^ . 

•  Select  the  PTM\New  Simulation  command.  This  will  create  an  empty  simulation  that  shows 
up  in  the  Project  Explorer  with  the  name  “PartSet.” 

•  Right-click  on  the  new  simulation  in  the  Project  Explorer  and  select  Rename.  Change  the 
name  of  the  particle  set  to  “Tides.” 

•  Select  the  PTM\Model  Control  command.  This  displays  the  PTM  Model  Control  dialog 
(Figure  6)  with  the  Hydrodynamic,  Sediment,  and  Source  inputs  tab  active.  Parameters  and 
file  names  must  be  provided  in  several  of  these  tabs  for  a  PTM  simulation.  These  are 
described  below. 

In  the  Hydrodynamic,  Sediment,  and  Source  inputs  tab,  specify  the  existing  files  that  will  be 
used  as  input  for  the  PTM  simulation.  Click  on  the  file  icon  next  to  Geometry  and  select 
“estuary.grd.”  This  prompts  the  PTM  to  use  this  grid  file  to  define  its  Eulerian  domain. 
Click  the  icon  next  to  XMDF  flow  file  and  select  the  file  “estuary_tide.h5.”  This  prompts 
PTM  to  use  this  file  as  a  source  of  hydrodynamic  data.  In  the  WSE  combo  box,  choose  the 
data  set  “tide  only  wse”  and  in  the  Velocity  combo  box  choose  the  “tide  only  velocity.” 
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At  the  bottom  section  of  the  dialog,  select  the  “Placement  Option  1”  coverage  (just  created) 
as  the  PTM  Coverage.  This  coverage  includes  the  line  sources  defined  above.  The  SMS  will 
convert  the  sources  defined  in  that  coverage  to  an  input  source  file  for  PTM.  It  will  have  the 
same  name  as  the  PTM  simulation  with  the  extension  “.source.” 


•  In  the  Hydro,  Sediment,  and  Source  inputs  tab,  click  on  the  Create  files  from  data  button.  A 
dialog  will  appear  (Figure  7).  This  allows  the  user  to  create  the  input  files  for  the  PTM.  The 
geometry  and  flow  files  already  exist  and  do  not  need  to  be  created  here.  However,  a 
sediment  file  must  be  created  to  define  the  native  sediments.  Click  on  the  “Select...  ”  button 
in  the  top  section  and  select  the  ADCIRC  mesh  that  is  loaded  into  SMS.  This  assures  that 
this  grid  is  the  computational  domain  that  will  be  used  for  the  PTM.  Set  the  Solution  time 
format  to  seconds.  Because  the  grid  is  already  in  ADCIRC  fort.  14  format,  and  the  flow  data 
are  already  in  an  XMDF  file,  do  not  select  the  toggles  to  create  geometry  and  flow  files. 


Select  the  Create  PTM  sediment  file  toggle  (near  the  bottom  in  Figure  7).  The  SMS  will 
create  a  sediments  file  based  on  user  input.  In  this  example,  no  spatially  varied  data  sets 
exist,  so  choose  “Constant”  and  “mobile  bed”  and  enter  the  three  values  of  native  bed 
sediment  parameters  as  shown  in  Figure  7.  If  data  sets  defining  varied  native  sediment  sizes 
had  existed,  the  user  could  set  the  toggle  box  to  “Varied”  and  choose  the  appropriate  data 
sets.  The  grain  size  values  are  used  by  PTM  to  compute  roughness  and  entrainment 
coefficients.  Next,  specify  a  name  for  the  sediment  file  just  generated  by  clicking  on  the  file 
icon  at  the  bottom  of  the  dialog,  assigning  the  name  as  “estuary”  for  the  sediment  file  name 
(“.sediments”  will  be  added  as  the  extension).  Click  the  OK  button  to  return  to  the  model 
control  dialog. 


Figure  6.  Selection  of  Hydro,  Sediment,  and 
Source  inputs  for  the  PTM 


Geometry 

Select. . .  |  Mesh 

Solution  time  format:  |  seconds  ▼ 

\~  Create  geometry  file  (ADCIRC  fort.  14  format) 

File  name:  yil 


Flow  file 

I-  Create  XMDF  flow  file 


Select  Dataset... 


|  No  dataset  selected 


Native  Sediments 
I*  Create  PTM  sediment  file 


Bed  type:  | Constant 

▼  I  |  mobile  bed  ▼  | 

D35:  |  0.13 

(mm) 

D50:  |  0. 19 

(mm) 

D90:  |  0.3 

(mm) 

File  name:  j  j|  C:VnodelsV>TM\GenericEstuary\Test\iestuary. sediments 

Help 

OK  |  Cancel 

Figure  7.  Defining  data  sources  for  the  PTM 
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•  Switch  to  the  Time  Control  tab  (Figure  8).  This  dialog  allows  the  user  to  coordinate  the  PTM 
simulation  with  the  hydrodynamics  and  specify  a  computational  time-step.  Enter  2/11/2004 
12:00:00  AM  for  the  Start  date/time  as  the  starting  time  for  the  PTM  simulation.  This  is  the 
earliest  time  any  particle  source  is  activated.  Next,  enter  2/12/2004  07:45:00  AM  for  the  End 
date/time.  This  is  the  time  that  the  PTM  simulation  will  end.  The  PTM  will  simulate  almost 
32  hr  of  particle  motion.  Set  the  computation  time-step  to  3  sec.  This  tells  the  PTM  to 
compute  particle  locations  every  3  sec.  Enter  2/09/2004  12:00:00  AM  for  the  Start  data/time 
of  the  hydro  data.  This  is  the  reference  time  for  the  ADCIRC  simulation. 

•  Switch  to  the  Computational  Parameters  tab  (Figure  9).  Change  the  Distribution  to  By 
weight,  and  Advection  to  Q3D  (quasi-3D)  (see  Demirbilek  et  al.  (2005a)  for  more 
information  on  advection  modes).  Set  the  Update  shears,  bedforms  and  mobility  every  field 
to  300  time-steps.  This  prompts  PTM  to  update  the  bed  every  15  min.  More  frequent 
updating  can  slow  down  computation.  The  other  values  can  be  left  as  the  defaults,  but  users 
can  change  these  as  necessary. 


PTM  Model  Control  (PartSet) 


Computational  Parameters  |  Output  Options  |  Waves  ]  Traps 
Hydro.  Sediment,  and  Source  inputs  Time  Control 


Start  date/time: 
End  date Aime : 


J02/11/2fflM  12::(M>::00  AM 
1 02/1 2/2M4  07:  :45: :»  AM 


Computational  time  step:  [^0  "  seconds 

Start  date.Time  for  hydro  data:  1 02/Q9/2DG4  1 2 : :(H}: :EH}  00 


Help 


OK 


Cancel 


Figure  8.  The  PTM  Time  Control  Dialog 


PTM  Model  Control 


Hydro.  Sediment,  and  Source  inputs  |  Time  Control 

Computational  Parameters  |  Output  Options  j  Waves  j  Traps 

Computation  Methods 
Distribution 


Eulerian: 


|  B1/  weight 

jPTM 

3 

Advection: 


"3 
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Computational  Parameters 
Minimum  depth: 


Temperature: 

Salinity: 

Horizontal  diffusion: 


0.01 


15.0 


34.0 


=C 

%* 


0.25 


0.008  EiS 


Vertical  diffusion: 

P  Hiding  and  exposure 
1^  Particle-bed  interaction 
W  Turbulent  shear  fluctuations 


Update  shears,  bedforms.  and  mobility  every  J3D0 


time  steps 


Help 


OK 


Cancel 


Figure  9.  The  PTM  Computational  Parameters 
Dialog 


•  Finally,  switch  to  the  Output  Options  tab  (Figure  10)  and  set  the  Grain  Size,  Mobility,  State, 
and  Parcel  Mass  toggles  to  “on.”  This  prompts  the  PTM  to  output  these  attributes  for  the 
particles  that  are  being  traced.  The  SMS  can  display  PTM  output  according  to  any  of  these 
settings  after  the  simulation  is  complete.  For  example,  the  particles  could  be  color-coded 
based  on  their  representative  grain  size  if  the  Grain  Size  toggle  is  on.  Also  enter  10  for  the 
Output  Increment  to  save  particle  locations  at  every  10  time-steps  or  30  sec.  This  completes 
the  setup  of  the  model  parameters  for  the  simulation.  Click  the  OK  button.  The  Traps  and 
Waves  tabs  will  not  be  used  in  this  example.  In  an  example  in  the  next  section,  waves  will  be 
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PTM  Model  Control 


Hydro,  Sediment,  and  Source  inputs  |  Time  Control 

Computational  Parameters  Output  Options  j  Waves  j  Traps 

Particle  Output 
P?1  Grain  size 


Output  increment: 
Every  [iG 


p  Mobility 
P  State 
I-  Source 
r  Velocities 
P  Parcel  mass 
Mapping  Output  (on  ADC  IRC  Grid] 
V~  Bedfomns 


time  steps 


!~~  Waves 
I-  Mobility 


included.  The  PTM  user  guides 
(Demirbilek  et  al.  2005a,  2005b)  provide 
more  details  about  options  that  are 
available  for  using  these  tabs. 

SAVE  THE  SIMULATION:  The  simulation 
data  specified  in  these  dialog  boxes  must  be 
saved  to  files  before  executing  the  PTM.  If 
the  user  forgets  this  step,  the  SMS  will  prompt 
to  save  the  simulation  before  allowing  the 
simulation  to  run.  To  save  a  simulation,  select 
File]  Save  New  Project  and  enter  the  name 
“estuary”  as  the  name  of  the  SMS  project  file 
(.sms). 

RUN  THE  PTM:  The  simulation  is  ready  to 
be  run.  This  simulation  takes  approximately 
10  to  15  min  to  compute  on  a  PC.  In  the  first 
few  minutes,  the  PTM  is  creating  an  element 
neighbor  table.  During  this  time,  it  may 
appear  that  the  application  has  stopped,  but  it 
is  still  working.  To  launch  the  PTM  model, 
select  the  PTM\Run  Model  command.  If  Figure  10.  The  PTM  Output  Options  Dialog 

needed,  the  SMS  will  bring  up  a  prompt  to  allow  the  user  to  select  the  directory  location  of  the 
PTM  executable  file.  Once  the  model  location  is  defined,  select  the  OK  button  to  launch  the 
model.  The  model  location  may  be  set  in  the  preferences,  in  which  case  the  SMS  will  launch  the 
model  directly  after  the  command  is  given.  A  dialog  appears  that  displays  a  progress  bar  of  the 
model  execution  status.  When  the  run  is  complete,  the  button  at  the  bottom  of  the  dialog 
changes  from  “Abort”  to  “Exit”  and  the  words  “Model  Finished”  will  appear  in  the  output 
window.  Select  the  Exit  button  to  close  the  model  execution. 


Mapping  output  increment 
Ever/  pC:C‘ 


time  steps 


Help 


OK 


Cancel 


READ  THE  SOLUTION:  The  PTM  creates  two  solution  files.  The  first  file  stores  the  particle 
data  (Lagrangian),  and  the  other  stores  the  mapped  Eulerian  data.  These  are  named  by  adding 
file  descriptors  to  the  simulation  name.  For  this  case,  the  file  “estuary_Tides_particles.h5” 
includes  the  particle  paths  and  attributes.  If  any  options  for  mapping  solution  data  to  the 
Eulerian  grid  had  been  selected,  the  PTM  would  have  written  a  file  named 
“estuary_Tides_maps.h5.”  Both  of  these  files  are  created  in  XMDF  format  (Jones  et  al.  2004). 
When  the  model  simulation  is  completed,  the  SMS  prompts  the  user  to  read  in  the  solution  files. 
The  solution  may  also  be  read  in  by  selecting  the  File\Open  command  from  the  menu  bar,  and  by 
choosing  the  binary  solution  file  “estuary_Tides_particles.h5.”  As  the  SMS  loads  this  file,  data 
sets  appear  in  the  Project  Explorer  (data  tree).  The  SMS  will  re-draw  (frame)  the  active  screen, 
since  new  data  have  been  added  to  the  project. 

VISUALIZE  THE  PARTICLES:  The  SMS  supports  multiple  methods  of  displaying  the 
particles  as  demonstrated  in  this  section.  To  view  the  options,  select  the  Display\Display 
Options  command  (Figure  11).  The  left  side  of  the  display  options  dialog  allows  the  user  to 
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control  the  display  of  the 
particle  head  and  tail.  Turn 
both  of  these  on.  Click  on 
the  symbol  next  to  the 
Particles  toggle  and  change 
the  symbol  to  a  4-pixel 
diamond  (as  shown).  The 
particles  and  their  tails  can 
be  color  coded.  This  coding 
can  be  based  on  any  of  the 
particle  attributes  or  data 
sets  saved  by  PTM.  For 
example,  the  user  may  want 
to  have  the  particles  colored 
based  on  the  characteristic 
grain  size  of  that  particle. 

If  there  are  multiple  sources, 
the  user  may  want  to  display 
particles  generated  at  each 
source  in  a  different  color.  Figure  11.  Particle  Display  Options  Dialog 

Each  of  these  attributes  or  data  sets  is  displayed  in  the  project  explorer.  The  “active”  data  set  or 
attribute  is  displayed  in  bold  text.  For  this  example,  change  both  the  Particles  and  the  Particle 
tails  to  display  the  “Active  data  set.”  This  tells  the  SMS  to  color  the  particles  based  on  whatever 
attribute/data  set  is  selected.  Set  the  Particle  Tail  Length  to  1,800  sec  (30  min).  This  option 
allows  the  user  to  control  the  length  of  the  particle  tail.  The  tail  indicates  the  speed  of  the 
particle.  In  the  upper  right  comer  of  the  dialog,  turn  off  the  toggle  to  display  Particle  pathlines. 
This  option  displays  the  entire  path  in  a  user-selected  color.  Normally,  this  option  has  the 
tendency  to  clutter  the  display,  but  it  is  useful  in  indicating  general  flow  patterns. 

The  options  in  the  lower  right  comer  of  the  dialog  allow  the  user  to  reduce  the  number  of 
particles  displayed.  For  this  case,  the  default  of  viewing  all  the  particles  is  appropriate.  Click 
the  OK  button  to  exit  this  dialog. 

Stepping  Through  Time.  Select  the  “grain  size”  data  set  in  the  project  explorer.  Particles 
will  be  displayed  in  red  (smaller  characteristic  grain  size)  to  yellow,  green,  and  blue 
(increasingly  higher  grain  size).  Click  the  time-step  for  2/1 1/2004  08:00:00  AM  to  set  the  time 
to  about  8  hr  into  the  simulation.  Use  the  down  arrow  to  step  through  the  time-steps  and  watch 
the  particles  move.  Note  that  updating  the  time  in  the  particle  module  does  not  currently  update 
the  time  in  the  mesh  module,  so  the  vectors  will  not  change.  The  feature  to  update  the  vector 
fded  will  be  added  with  a  future  release.  The  vectors  do  change  when  generating  an  animation 
as  will  be  shown  below.  Figure  12  shows  the  particles  approximately  8  hr  into  simulation  time. 


Display  Options 


General  |  2D  Mesh  |  Boundary  Grid  |  Cartesian  Grid  |  Scatter  |  Map  ]  1 D 

Contour  Options  |  Vectors  j  Cascade  Grid  Particles 

Particle  Set  these  display  options  will  be  applied  to:  PartSet  (2) 


O  I  -  Particles 


Color  based  on: 

|. Active  data  set 

Select  Set... 

Color  Options... 

Particle  tails 

Length:  |l S-DCI.O 

seconds 

I-  Include  symbol  at  time  step  positions 

Color  based  on: 

[.Active  data  set 

Select  Set... 

Color  Options...  | 

.All  off 


.All  on 


Jd  r 


Particle  path  lines 


Particle  Display  Filter 
Number  of  particles:  525 
Display  every  1 


particle 


Begin  with  particle:  |1 
End  with  particle:  [525 


Help 


OK 


Cancel 
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Creating  an  Animation.  The  SMS  includes  the  tools  required  to  create  animations  of  the 
particles  and  flows.  When  creating  an  animation,  the  SMS  loops  through  a  time  range  to  create  a 
user-controlled  number  of  snapshots  or  frames,  and  saves  these  images  to  an  “avi”  file.  The 
animation  sequences  are  illustrated  next: 

•  Ensure  you  are  viewing  the  region  of  the  domain  you  wish  to  see.  Select  a  region  similar  to 
that  shown  in  Figure  12  to  see  the  range  of  particle  motion. 

•  Select  the  Data\Film  loop,  command.  The  dialog  that  appears  allows  you  to  select  the  type  of 
film  loop  and  the  file  name  to  save.  Use  the  defaults  and  click  on  the  Next  button. 

•  The  start  time  and  end  time  should  be  set  to  match  the  entire  simulation.  To  tell  the  SMS  to 
animate  the  Eulerian  data,  be  sure  to  select  the  Animate  Mesh  Data  toggle  and  enter  the 
reference  hydro  time  as  02/09/2004  12:00:00  AM  (the  starting  hydro  time).  Select  the  option 
to  Specify  Number  of  Frames  and  enter  100.  Click  Next. 

•  Click  on  the  Clock  Options  button.  In  the  dialog  that  appears,  select  Show  Progress  Bar  and 
choose  the  type  to  be  “Horizontal  Progress  Type.”  Set  the  size  to  50  and  click  OK.  Click 
Finish  in  the  Film  Loop  Setup. 

As  the  animation  is  generated,  which  may  take  a  few  minutes,  it  is  also  saved  to  the  disk.  After 
the  generation  is  completed,  the  SMS  launches  the  animation  in  the  viewer  PAVIA.exe  that  is 
distributed  with  the  SMS.  The  animation  shows  that  particles  in  the  mouth  of  the  estuary  are 
washed  into  and  then  back  out  of  the  estuary  and  distribution  of  particles  varies  temporally  and 
spatially.  As  the  velocities  decrease  in  the  mouth  of  the  estuary,  smaller  particles  also  start 
settling  down.  Users  should  close  the  animation  after  viewing  and  continue  with  the  tutorial. 

WAVES:  The  existing  PTM  simulation  will  now  be  copied  and  modified  to  include  waves.  To 
include  waves,  users  must  have  results  from  a  previously  run  STWAVE  simulation,  and  possibly 
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a  modified  hydrodynamic  output  that  included  the  wave  data.  The  PTM  will  then  be  rerun  using 

both  the  modified  hydrodynamic  solution  and  the  wave  solution  data.  The  steps  to  be  followed 

are  described  below: 

•  Open  the  STWAVE  simulation  by  selecting  the  File\Open  command  and  select 
estuarystwave.sim  (also  included  with  SMS  version  9.0  tutorials).  Click  the  OK  button. 
This  provides  the  basis  for  wave  data  that  will  be  included  in  the  PTM  simulation.  You  may 
need  to  go  into  the  display  options  and  turn  off  the  cells  of  the  stwave  grid. 

•  Open  the  ADCIRC  solution  that  was  run  to  include  the  influence  of  waves  by  selecting  the 
File\Open  command.  Select  estuary_waves.h5  (also  included  with  SMS  version  9.0 
tutorials).  Click  the  OK  button. 

•  Right-click  on  the  PTM  simulation  in  the  Project  Explorer  (tree)  and  select  “Copy 
Simulation.”  This  will  create  a  copy  of  the  simulation  just  constructed. 

•  Right-click  on  this  new  simulation,  which  will  be  named  “PartSet  (2)”  automatically  by  the 
SMS,  and  select  the  Rename  command.  Change  the  name  to  “Waves.” 

•  Select  this  new  simulation,  by  clicking  on  its  name  in  the  Project  Explorer.  Now  choose  the 
PTM\Model  Control  menu  command  to  modify  simulation  input. 

•  In  the  Hydrodynamic,  Sediment,  and 
Source  inputs  tab  (Figure  6),  select  the 
ADCIRC  solution  sets  that  include  the 
influence  of  waves  on  hydrodynamics. 

Next  to  the  XMDF  flow  file,  click  on  the 
icon  and  choose  the  file  estuary _waves.h5 . 

In  the  WSE  combo  box,  select  “waves 
wse”  for  water  surface  elevation. 

Similarly,  select  “Datasets/waves  velocity” 
in  the  Velocity  combo  box.  The  sediment 
sources  and  grid  files  can  remain  the  same. 

•  Click  on  the  Waves  tab  (Figure  13).  Check 

the  toggle  box  to  use  waves,  and  click  on 
the  From  STWA  VE  Grid  button.  This  fills 
in  the  origin  and  orientation  of  the  wave 
simulation  based  on  the  STWAVE 

simulation,  which  was  loaded  into  the 

SMS  in  step  1.  Click  on  the  icon  in  the 
Solution  data  section  and  select  the  file 
“estuary_waves.wav.” 

•  In  the  lower  portion  of  the  dialog,  enter 
the  Start  Date/Time  of  2/09/2004  12:00:00 
AM.  This  specifies  that  the  wave  data  shall  start  at  the  same  time  as  the  hydrodynamic  data. 

•  Enter  the  Time  between  spectra  as  02:00:00  (i.e.,  waves  are  updated  every  2  hr)  and  the 
Number  of  Spectra  in  File  as  50  (i.e.,  50  wave  conditions  are  simulated).  Note  that  this 


PTM  Model  Control  (Waves)  fxl 


Figure  13.  Wave  specification  in  the  PTM 
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information  comes  from  the  STWAVE  run.  Click  the  OK  button  to  exit  the  Model  Control 
dialog. 

SAVE  THE  SIMULATION:  Now  resave  the  simulation  before  running  the  PTM.  Select 
File\Save  to  update  the  estuary. sms  project  file  saved  earlier. 


RUN  THE  PTM:  The  simulation  with  waves  is  ready  to  be  run.  This  simulation  takes 
approximately  15  min  to  compute  on  a  3-GHz  PC.  Read  in  the  solution  of  this  simulation  using 
steps  described  earlier  and  view  the  particle  motion  as  affected  by  waves.  The  solution  file  name 
is  “estuary_Waves_particles.h5.”  User  will  note  that  the  wave  action  greatly  influences  particle 
activity  near  the  placement  site. 


MAP  THE  PARTICLES  TO  A  GRID:  The  results  of  the  PTM  simulation  can  also  be 
transferred  onto  a  Cartesian  grid  for  visualization  of  the  Eulerian  output.  Presently,  this 
methodology  only  supports  the  particle  counts,  and  will  be  enhanced  in  the  future  to  create  data 
sets  for  deposition  depth,  suspended  sediment  mass,  and  suspended  sediment  concentration.  To 
utilize  this  feature,  a  Cartesian  grid  must  be  created  or  loaded  into  the  SMS.  This  example  will 
use  the  STWAVE  grid  to  visualize  the  particle  counts  as  follows: 

•  In  the  Particle  module  ^  select  the  Data\Compute  Grid  Data  Sets  command.  This  creates 
data  sets  for  the  Cartesian  grid  that  can  now  be  contoured. 


•  Switch  to  the  Cartesian  Grid  module  3.  In  Display  Options,,  turn  on  Cartesian  grid 
contours.  You  can  now  select  various  time-steps  to  see  the  number  of  particles  in  each  cell  in 
the  grid. 


SUMMARY:  This  technical  note  provides  instructions  for  developing  a  PTM  simulation.  A 
typical  project  could  include  many  particle  sources  and  wave  and  velocity  fields.  In  such  cases, 
it  would  be  necessary  to  perform  multiple  runs  and  some  variation  in  the  procedure  and  tools 
described  here  would  be  required.  The  development  of  the  PTM  is  ongoing,  and  the  interface  is 
also  expected  to  change.  Future  technical  notes  will  describe  changes  to  the  updated  versions  of 
the  model  and  their  SMS  interface.  Feedback  and  suggestions  from  users  are  welcome  on  the 
design,  implementation,  and  usage  of  the  PTM  and  this  tutorial. 

POINTS  OF  CONTACT:  This  technical  note  was  written  by  Dr.  Zeki  Demirbilek,  email: 
Zeki.Demirbilek@erdc.usace.army.mil),  Tel:  601-634-2834,  Fax:  601-634-4033;  Mr.  Jarrell 
Smith  (Jarrell.Smith@erdc.usace.army.mil)  of  the  U.S.  Army  Engineer  Research  and 
Development  Center  (ERDC),  Coastal  and  Hydraulics  Laboratory,  and  Dr.  Alan  Zundel 
(zundel@byu.edu)  and  Mr.  Russell  Jones  (riones@byu.edu)  of  Brigham  Young  University,  and 
Dr.  Neil  MacDonald  and  Mr.  Michael  Davies  of  the  Pacific  International  Engineering,  PLLC. 
Questions  about  this  technical  note  can  be  addressed  to  Dr.  Demirbilek  or  to  the  Program 
Manager  of  the  Dredging  Operations  and  Environmental  Research  (DOER)  Program,  Dr.  Robert 
M.  Engler  (601-634-3624,  Robert.M.Engler@erdc.usace.army.mil).  This  technical  note  should 
be  referenced  as  follows: 
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Demirbilek,  Z.,  Smith,  S.  J.,  Zundel,  A.  K.,  Jones,  R.  D.,  McDonald,  N.  J.,  and  Davies, 

M.E.  (2005).  “Particle  Tracking  Model  (PTM)  in  the  SMS:  III.  Tutorial  with 
examples,”  Dredging  Operations  and  Engineering  Research  Technical  Notes 
Collection  (ERDC  TN-DOER-D6),  U.S.  Army  Engineer  Research  and  Development 
Center,  Vicksburg,  MS.  An  electronic  copy  of  this  TN  is  available  at  (http://el.erdc. 
usace.army.mil/dots/doer/.) 
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